Overview

Circuit arguments provide a convenient means to enable the user of a circuit definition to specify custom parameters to configure the circuit behavior. They can be retrieved within active objects by user code to parameterize the processing or provided as attribute values for the definition's child objects (e.g. the dimensionality of a method).

Circuit arguments are initialized by the instantiator on instance creation and stored in the circuit definition's class data. The definition can then access them using generated member functions wherever required. As a result of these arguments being stored, they must also be typed and they can also optionally be defaulted.

Defining Circuit Arguments

Circuit arguments are defined in the Circuit Definition Properties window as Parameters:

In the popup Parameters editor window, you can specify each argument's type, name, whether it is optional and its default value. These parameters are passed into the circuit via the circuit Create() to initialize internal values. Any function within the circuit can then access the parameters via one of the two generated access functions:

<type> get_<name>()
void set_<name>( <type> value )

Similarly any child object within the Circuit can also access the parameters, via its Parent() function:

<type> Parent().get_<name>()
void Parent().set_<name>( <type> value )

These functions can also be used as parameters to child objects via the objects' Properties window, as long as a MACRO is defined in a header file:

#define RUN_TIME_PRIO (Parent().get_RunTimePrio())

Method Priority : RUN_TIME_PRIO

Initializing Circuit Arguments

To initialize the circuit arguments we need to specify their values where the circuit is instantiated.

The value specified can be any numerical value (appropriate for the type) or a macro definition.

eg.

Arg2 = MY_ARG_2

where MY_ARG_2 is a macro defined in a header file (eg ProjectHeaders.hpp)

#define MY_ARG_2 (ClpNumProcessors())

When we are instantiating an array of circuits, each circuit element will get a copy of the instantiated values (NB set_<name>() will only reset the value in a single element of the circuit).

Nesting

Child circuits can access their parent arguments by use of a Parent().get_<name> macro

eg.

Arg2 = MY_ARG_2

where MY_ARG_2 is a macro defined in a header file (eg ProjectHeaders.hpp)

#define MY_ARG_2 (Parent().get_Arg2())

Runtime Arguments

To define arguments that are to be populated at runtime, it is possible to set attributes to parameters that are initialized in the OnPrestart() function for the process.

eg.

Arg2 = gArg2

ProjectHeader.hpp

extern float gArg2;

<ProcessName>Process.cpp

float gArg2 = 0.0f;

bool Process1Process::OnPrestart()
{
   bool failed = false;

   Process1ProcessBase *processBase = (Process1ProcessBase*)m_processBase;

   failed |= ( processBase->OnPrestart() == FALSE );

   // TODO: Add custom create code

   // read global params from file
   FILE* fp = fopen( "./MyApp.ini", "r" );
   fscanf( fp, "%f", &gArg2 );
   fclose( fp );

   return ! failed;
}

For more information see Setting Attributes at Runtime.

Blueprint Help	Send comments on this topic.
Circuit Arguments